---
title: NumberField
description: NumberField allows a user to enter a number, and increment or decrement the value using stepper buttons.
links:
  - label: Aria docs
    href: https://react-spectrum.adobe.com/react-aria/NumberField.html
  - label: Report an issue
    href: https://github.com/mehdibha/dotUI/issues/new/choose
  - label: Edit this page
    href: https://github.com/mehdibha/dotUI/tree/main/content/components/inputs/number-field.mdx?plain=1
---

<ComponentPreview
  name="number-field/demos/default"
  preview={`<NumberField label="Width" defaultValue={1024} />`}
/>

## Installation

```package-install
npx shadcn@latest add @dotui/number-field
```

## Usage

Use a `NumberField` to allow a user to enter a number.

## Options

### Number formatting

The NumberField value can be formatted by using the `formatOptions` prop. formatOptions is compatible with the option parameter of [Intl.NumberFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat) and is applied based on the current locale.

<ComponentPreview
  name="number-field/demos/format-options"
  preview={`<NumberField
    label="Decimal"
    defaultValue={0}
    formatOptions={{
      signDisplay: "exceptZero",
      minimumFractionDigits: 1,
      maximumFractionDigits: 2,
    }}
  />
  <NumberField
    label="Percentage"
    defaultValue={0.05}
    formatOptions={{
      style: "percent",
    }}
  />
  <NumberField
    label="Currency"
    defaultValue={45}
    formatOptions={{
      style: "currency",
      currency: "EUR",
      currencyDisplay: "code",
      currencySign: "accounting",
    }}
  />
  <NumberField
    label="Unit"
    defaultValue={4}
    formatOptions={{
      style: "unit",
      unit: "inch",
      unitDisplay: "long",
    }}
  />`}
/>

### Size

Use the `size` prop to control the size of the `NumberField`. The default size is `"md"`.

<ComponentPreview
  name="number-field/demos/sizes"
  preview={`<NumberField size="sm" />
<NumberField size="md" />
<NumberField size="lg" />`}
/>

### Label

A visual label can be provided for the `NumberField` using the `label` prop or a hidden label using `aria-label` prop.

<ComponentPreview
  name="number-field/demos/label"
  preview={`<NumberField label="Width" />
<NumberField aria-label="Width" />`}
/>

### Description

A description can be supplied to a NumberField via the `description` prop. The description is always visible unless the `isInvalid` prop is set to `true` and an error message is provided.

<ComponentPreview
  name="number-field/demos/description"
  preview={`<NumberField label="Width" description="Enter the desired width." />`}
/>

### Error message

An `errorMessage` can be supplied to a `NumberField`, which will be displayed when the `isInvalid` prop is set to `true`.

<ComponentPreview
  name="number-field/demos/error-message"
  preview={`<NumberField
    label="Width"
    isInvalid
    errorMessage="Please fill out this field."
  />`}
/>

### Disabled

Use the `isDisabled` prop to disable the NumberField.

<ComponentPreview
  name="number-field/demos/disabled"
  preview={`<NumberField isDisabled />`}
/>

### ReadOnly

The `isReadOnly` boolean prop makes the NumberField's text content immutable. Unlike `isDisabled`, the NumberField remains focusable and the contents can still be copied.

<ComponentPreview
  name="number-field/demos/read-only"
  preview={`<NumberField isReadOnly />`}
/>

### Required

Use the `isRequired` prop to mark the NumberField as required.
Use the `necessityIndicator` prop to control the visual style of the required state.

<ComponentPreview
  name="number-field/demos/required"
  preview={`<NumberField label="Width" isRequired />
<NumberField label="Width" isRequired necessityIndicator="icon" />
<NumberField label="Width" isRequired necessityIndicator="label" />
<NumberField label="Width" necessityIndicator="label" />`}
/>

## Uncontrolled

Use the `defaultValue` prop to set the default input value.

<ComponentPreview
  name="number-field/demos/uncontrolled"
  preview={`<NumberField defaultValue={80} />`}
/>

## Controlled

Use the `value` and `onChange` props to control the value of the input.

<ComponentPreview
  name="number-field/demos/controlled"
  preview={`const [value, setValue] = React.useState(69);
return <NumberField value={value} onChange={setValue} />;`}
/>

## Composition

If you need to customize things further, you can drop down to the composition level.

<ComponentPreview
  name="number-field/demos/composition"
  preview={`<NumberFieldRoot>
    <Label>Quantity</Label>
    <Group className="flex items-center gap-2">
      <Button slot="decrement">
        <MinusIcon />
      </Button>
      <InputRoot>
        <Input />
      </InputRoot>
      <Button slot="increment">
        <PlusIcon />
      </Button>
    </Group>
    <Description>Enter the disired quantity.</Description>
  </NumberFieldRoot>`}
/>

## API Reference

| Prop                 | Type                                                                                                     | Default  | Description                                                                                                                                                                                                                           |
| -------------------- | -------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `size`               | `"sm" \| "md" \| "lg"`                                                                                   | `"md"`   | The size of the input.                                                                                                                                                                                                                |
| `label`              | `ReactNode`                                                                                              |          | The content to display as the label.                                                                                                                                                                                                  |
| `description`        | `ReactNode`                                                                                              |          | A description for the field. Provides a hint such as specific requirements for what to choose.                                                                                                                                        |
| `errorMessage`       | `ReactNode \| (v: ValidationResult) => ReactNode`                                                        |          | An error message for the field.                                                                                                                                                                                                       |
| `decrementAriaLabel` | `string`                                                                                                 | -        | A custom aria-label for the decrement button. If not provided, the localized string "Decrement" is used.                                                                                                                              |
| `incrementAriaLabel` | `string`                                                                                                 | -        | A custom aria-label for the increment button. If not provided, the localized string "Increment" is used.                                                                                                                              |
| `isWheelDisabled`    | `boolean`                                                                                                | -        | Enables or disables changing the value with scroll.                                                                                                                                                                                   |
| `formatOptions`      | `Intl.NumberFormatOptions`                                                                               | -        | Formatting options for the value displayed in the number field. This also affects what characters are allowed to be typed by the user.                                                                                                |
| `isDisabled`         | `boolean`                                                                                                | -        | Whether the input is disabled.                                                                                                                                                                                                        |
| `isReadOnly`         | `boolean`                                                                                                | -        | Whether the input can be selected but not changed by the user.                                                                                                                                                                        |
| `isRequired`         | `boolean`                                                                                                | -        | Whether user input is required on the input before form submission.                                                                                                                                                                   |
| `isInvalid`          | `boolean`                                                                                                | -        | Whether the value is invalid.                                                                                                                                                                                                         |
| `validate`           | `(value: string) => ValidationError \| true \| null \| undefined`                                        | -        | A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if validationBehavior="native". For realtime validation, use the isInvalid prop instead. |
| `autoFocus`          | `boolean`                                                                                                | -        | Whether the element should receive focus on render.                                                                                                                                                                                   |
| `value`              | `number`                                                                                                 | -        | The current value (controlled).                                                                                                                                                                                                       |
| `defaultValue`       | `number`                                                                                                 | -        | The default value (uncontrolled).                                                                                                                                                                                                     |
| `minValue`           | `number`                                                                                                 | -        | The smallest value allowed for the input.                                                                                                                                                                                             |
| `maxValue`           | `number`                                                                                                 | -        | The largest value allowed for the input.                                                                                                                                                                                              |
| `step`               | `number`                                                                                                 | -        | The amount that the input value changes with each increment or decrement "tick".                                                                                                                                                      |
| `validationBehavior` | `'native' \| 'aria'`                                                                                     | 'native' | Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.                                                                        |
| `name`               | `string`                                                                                                 | -        | The name of the input element, used when submitting an HTML form.                                                                                                                                                                     |
| `children`           | `ReactNode \| (values: NumberFieldRenderProps & {defaultChildren: ReactNode \| undefined}) => ReactNode` | -        | The children of the component. A function may be provided to alter the children based on component state.                                                                                                                             |
| `className`          | `string`                                                                                                 | -        | The CSS className for the element.                                                                                                                                                                                                    |
| `style`              | `CSSProperties \| (values: NumberFieldRenderProps & {defaultStyle: CSSProperties}) => CSSProperties`     | -        | The inline style for the element. A function may be provided to compute the style based on component state.                                                                                                                           |

| Event                 | Type                                        | Description                                                                                                      |
| --------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `onFocus`             | `(e: FocusEvent<Target>) => void`           | Handler that is called when the element receives focus.                                                          |
| `onBlur`              | `(e: FocusEvent<Target>) => void`           | Handler that is called when the element loses focus.                                                             |
| `onFocusChange`       | `(isFocused: boolean) => void`              | Handler that is called when the element's focus status changes.                                                  |
| `onKeyDown`           | `(e: KeyboardEvent) => void`                | Handler that is called when a key is pressed.                                                                    |
| `onKeyUp`             | `(e: KeyboardEvent) => void`                | Handler that is called when a key is released.                                                                   |
| `onChange`            | `(value: T) => void`                        | Handler that is called when the value changes.                                                                   |
| `onCopy`              | `ClipboardEventHandler<HTMLInputElement>`   | Handler that is called when the user copies text.                                                                |
| `onCut`               | `ClipboardEventHandler<HTMLInputElement>`   | Handler that is called when the user cuts text.                                                                  |
| `onPaste`             | `ClipboardEventHandler<HTMLInputElement>`   | Handler that is called when the user pastes text.                                                                |
| `onCompositionStart`  | `CompositionEventHandler<HTMLInputElement>` | Handler that is called when a text composition system starts a new text composition session.                     |
| `onCompositionEnd`    | `CompositionEventHandler<HTMLInputElement>` | Handler that is called when a text composition system completes or cancels the current text composition session. |
| `onCompositionUpdate` | `CompositionEventHandler<HTMLInputElement>` | Handler that is called when a new character is received in the current text composition session.                 |
| `onSelect`            | `ReactEventHandler<HTMLInputElement>`       | Handler that is called when text in the input is selected.                                                       |
| `onBeforeInput`       | `FormEventHandler<HTMLInputElement>`        | Handler that is called when the input value is about to be modified.                                             |
| `onInput`             | `FormEventHandler<HTMLInputElement>`        | Handler that is called when the input value is modified.                                                         |

| Data attribute    | Description                         |
| ----------------- | ----------------------------------- |
| `[data-disabled]` | Whether the text field is disabled. |
| `[data-invalid]`  | Whether the text field is invalid.  |
